The 640 MEG Shareware Studio 2

home *** CD-ROM | disk | FTP | other *** search

/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / bbs / pb_122.zip / PB122SDK.DOC < prev next >

Wrap

Text File | 1992-08-17 | 56KB | 1,774 lines

██████ ██████ ███ ██ ██ ██ ██ ██ ██ ██ ██ ███ ████ ██ ██ ████ ████ ██ ███ ██ █████ ███ ██ ██ ██ █████ ██ ██ ██ ███ ██ █████ ██ ██ ██ ██ ██ ██ ██ ██ ██ █████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ████ ████ ██████ ████ ██████ ████ ██████ Software Developer's Kit Version 1.22 August 17, 1992 Copyright (c) 1991-1992 Philippe Leybaert All rights reserved ╒══════════════════════════════════════════════════════════════════╕ │░░░░░░ PROBOARD SOFTWARE DEVELOPMENT KIT VERSION 1.22 ░░░░░░░░░░░░│ ╘══════════════════════════════════════════════════════════════════╛ Included with ProBoard is a C library that allows you to write your own extensions to ProBoard in C or C++. All you need is an ANSI-compatible C or C++ compiler. The programs you create can be run within ProBoard by executing a new menu function. The ProBoard SDK files included with ProBoard are free software, so anyone who does not use ProBoard to run a BBS on a regular basis, but wants to write extension files, is allowed to do so without registering ProBoard. You can distribute any ProBoard extension files (PEX files) royalty-free. As far as we are concerned, any program you develop with the ProBoard SDK is your property. ┌──────────────────────────────────────────────────────────────────┐ │ Requirements │ └──────────────────────────────────────────────────────────────────┘ To create your own programs you need: - An ANSI compatible C or C++ compiler. Compilers known to be compatible with the ProBoard SDK are: - Zortech C/C++ 2.0 - 3.0 - Microsoft C 5.1 - 6.0 - Borland C++ 2.0 - 3.1 - Turbo C++ 1.0 - Turbo C 1.0 - 2.0 Other compilers may work too, but were not tested. - An MS-compatible linker (usually the one that came with your compiler). Linkers known to work with the ProBoard SDK are: - All Microsoft Linkers (LINK.EXE) - Borland's Turbo Link (TLINK) - Zortech's BLINK - The ProBoard SDK include file PB_SDK.H - The ProBoard SDK library PB_SDK.LIB - 1 - ┌──────────────────────────────────────────────────────────────────┐ │ Creating ProBoard Executables (PEX-files) │ └──────────────────────────────────────────────────────────────────┘ To create your own ProBoard executable (.PEX file), you first create a source file, say MYPROG.C. When ProBoard loads a PEX file, it executes the function main() in your program. This function is defined as: void main(int argc,char *argv[]) { ... } The parameters 'argc' & 'argv' contain optional data that can be given to your program at load time (exactly like C's argc and argv parameters). Creating this main() function is the only thing you need to do to write a valid ProBoard executable. From this point on, it's just like writing a regular C program. Most of the ANSI standard library functions are available, plus many ProBoard- specific functions and global variables, used for interfacing between your program and the ProBoard environment. As in a regular executable, you can build your program from several source files. This is a tiny sample ProBoard program: #include "pb_sdk.h" void main() { printf("You have %d minutes left.\n",TimeLeft()); AddTime(10); printf("Now you have %d minutes left.\n",TimeLeft()); } Included with ProBoard are a few example programs (in source form of course). - 2 - ┌──────────────────────────────────────────────────────────────────┐ │ Compiling and Linking │ └──────────────────────────────────────────────────────────────────┘ ProBoard executables have to be compiled using the LARGE memory model. For example (Turbo C++) : tcc -c -ml myprog.c Once you have your .OBJ file (in this case MYPROG.OBJ), you have to link it with the ProBoard SDK library (PB_SDK.LIB). You have to specify a filename as output filename. The linked executable must have extension .PEX. It is important to disable linking of the default compiler libraries!! It is also required to turn on case sensitivity. e.g. Turbo C++ : TLINK MYPROG,MYPROG.PEX,,PB_SDK /N /C Microsoft : LINK MYPROG,MYPROG.PEX,,PB_SDK /NOD /NOI; Zortech : BLINK MYPROG,MYPROG.PEX,,PB_SDK /NOD /NOI; That's all there is to it. Now you can run your program through ProBoard's menu function 60. I will now give the compiler syntax for some popular compilers: Zortech C/C++ : ztc -c -a -ml myprog.c Microsoft C : cl -Zep -Gs -c -AL myprog.c Turbo C/C++ : tcc -c -ml myprog.c Borland C++ : bcc -c -ml myprog.c And linker syntax: Borland : TLINK MYPROG,MYPROG.PEX,,PB_SDK /N /C Microsoft : LINK MYPROG,MYPROG.PEX,,PB_SDK /NOD /NOI; Zortech : BLINK MYPROG,MYPROG.PEX,,PB_SDK /NOD /NOI; ┌──────────────────────────────────────────────────────────────────┐ │ Restrictions │ └──────────────────────────────────────────────────────────────────┘ There are few restrictions in writing ProBoard executables. For C programs there are actually only two major restriction: long math & floating point operations. - 3 - Due to the fact that all compilers generate function calls to multiply, divide and shift long integers, and that every compiler vendor uses its own array of functions, it is impossible to include these functions in the ProBoard SDK. As a result, it is not directly possible to perform these operations on long values (eg. long1 = long2 * long3). However, we did include functions to perform these operations, but you will have to call these functions explicitly (eg. long1 = l_mul(long2,long3)). People who know their compiler well, can work around this problem by extracting the long math functions from the standard library, and linking them with the PEX file. For example, the long math functions used by the Zortech compiler are in the module LMATH.OBJ, located in the library ZLC.LIB. Extracting this module is as simple as : ZORLIB ZLS *LMATH; These are the ProBoard long math functions that you can use: long l_mul(long1,long2) Multiply 2 long values = long1 * long2 long l_div(long1,long2) Divide 2 long values = long1 / long2 long l_mod(long1,long2) Modulo of 2 long values = long1 % long2 long l_shl(long1,int1) Left shift a long value = long1 << int1 long l_shr(long1,int1) Right shift a long value = long1 >> int1 The functions l_div(), l_mod(), l_shl() and l_shr() are also available for unsigned long values: ul_div(), ul_mod(), ul_shl() and ul_shr(). Floating point operations are NOT supported. So it is not possible to use 'double' and 'float' variables & constants. Another major restriction only affects C++ programs. In a ProBoard C++ program, you can't declare global variables that have constructors or destructors (ie. no static constructors & destructors). So this will compile fine, but will certainly crash your machine: class myclass { int a; public: x() { .... some action .... } ~x() { .... some action .... } }; myclass some_global_object; main() { ... } - 4 - You can, however, use objects with constructors and destructors, as long as they are declared within a function. So this would work: main() { myclass some_local_object; .... } ┌──────────────────────────────────────────────────────────────────┐ │ Library functions supported │ └──────────────────────────────────────────────────────────────────┘ Almost all standard library functions are supported. Note that all functions that write to the standard output device (printf, putchar,...) write their output to the ProBoard window and to the user (through the modem). Functions that read from the standard input device and from the keyboard are NOT supported. (scanf,getch,gets,...) We provide substitutes for these functions. Functions supported: fopen , freopen , fseek , ftell , fgets , fgetc , fflush fclose , fputs , getc , getchar , gets , fputc , putc , putchar , puts , fread , fwrite , printf , fprintf , vfprintf , vprintf , sprintf , vsprintf , setbuf , setvbuf , remove , rename , rewind , clearerr , feof , isalpha , iscntrl , isdigit , isgraph , islower , isprint , ispunct , isspace , isupper , isxdigit , toupper , tolower , int86x , intdos , intdosx , dos_findfirst , dos_findnext , write , open , creat , close , unlink , chsize , dup , dup2 , lseek , access , filesize , filelength , isatty , atoi , atol , strtol , rand , srand , calloc , free , malloc , realloc , putenv getenv , abs , labs , memcpy , memmove , strcpy , strncpy , strcat , strncat , memcmp , strcmp , strncmp , memchr , strchr , strcspn , strpbrk , strrchr , strspn , strstr , strtok , memset , strlen , memicmp , stpcpy , strcmpl , strnicmp , strdup , strlwr , strupr , strnset , strrev , strset , swab , strncmpl , strnicmp , clock , time , mktime , asctime , ctime , localtime , gmtime , strftime , sleep , usleep , msleep , difftime For information on these functions, consult your compiler's library reference manual. - 5 - In the string output functions (printf and puts), you can use the following control codes in your string: \001 or \x01 Set output color to red :::: :::: :::: :::: \007 or \x07 Set output color to white \x11 to \x17 Same as \1 to \7, but blinking colors \t Stops output of string until user presses [Enter] \f Clears the user's screen (if enabled in the user's record) NOTE: Do NOT include any standard include files from your compiler. The only include file you can use is PB_SDK.H. THAT'S IT!! - 6 - ┌──────────────────────────────────────────────────────────────────┐ │ ProBoard Interface Functions │ └──────────────────────────────────────────────────────────────────┘ This is a list of all the functions that can be used to interface with ProBoard. Several types have been defined in the file PB_SDK.H bool : a boolean value that can have the values TRUE or FALSE byte : an unsigned character (8 bits) KEY : used for key scan codes (for sysopkey handlers and the ScanKey() function). ------------------------------------------------------------------ void AddTime(int min); ------------------------------------------------------------------ Adds 'min' minutes to the user's time left. If 'min' is negative, the number of minutes will be subtracted from the time left. Examples: AddTime(10); /* Adds 10 minutes */ AddTime(-5); /* Subtracts 5 minutes */ ------------------------------------------------------------------ int TimeLeft(void); ------------------------------------------------------------------ Returns the time left in minutes for the current user. ------------------------------------------------------------------ int TimeOnline(void); ------------------------------------------------------------------ Returns the time in minutes that the current user is online. ------------------------------------------------------------------ void SuspendTimer(void); ------------------------------------------------------------------ Suspends the online-timer for the current user. No time will be subtracted until RestartTimer() is called. - 7 - ------------------------------------------------------------------ void RestartTimer(void); ------------------------------------------------------------------ Restarts the timer after a call to SuspendTimer(). ------------------------------------------------------------------ void AdjustTime(void); ------------------------------------------------------------------ Call this function if you changed the user's level. This recalculates all limits (time,download,...). ------------------------------------------------------------------ void MsgEd(void); ------------------------------------------------------------------ Fires up the internal message editor or the fullscreen editor, depending on the settings of the user. The message will be stored in the file MSGTMP in the current directory. If a message is aborted, the file MSGTMP will be deleted by the message editor. If you create a MSGTMP file before invoking the message editor, this file will be used as a 'quote' message. ------------------------------------------------------------------ int PostMessage(char *from,char *to,char *subject,int area, bool pvt); ------------------------------------------------------------------ Posts a message to a user. from = Name of the sender to = Name of the user you're sending the message to subject = Subject of the message area = Message area number where the message has to be posted in. pvt = Private status (TRUE=private, FALSE=public) No checking is performed on any of the parameters! Return value: -1 on error 0 if ok - 8 - ------------------------------------------------------------------ int PostNetmail(char *from,char *to,char *subject,int area, FIDO_NODE *address,bool attach,bool crash, bool kill); ------------------------------------------------------------------ Posts a netmail message. from = Name of the sender to = Name of the user you're sending the message to subject = Subject of the message area = Message area number where the message has to be posted in address = Destination node number of this message. attach = TRUE for a file attach message crash = TRUE if this message is a crashmail message kill = TRUE if the message has to be deleted after it is sent FIDO_NODE is a structure with the following fields: struct { unsigned zone; /* Zone number */ unsigned net; /* Net number */ unsigned node; /* Node number */ unsigned point; /* Point number */ } No checking is performed on any of the parameters! Return value: -1 on error 0 if ok - 9 - ------------------------------------------------------------------ int ReadMsgArea(int area,MSGAREA *ma); ------------------------------------------------------------------ Reads data about a message area. area = Message area number (1-200) ma = Pointer to a MSGAREA structure to be filled Check the file PB_SDK.H for details about the MSGAREA structure definition. Return value: -1 if not defined 0 if read ok ------------------------------------------------------------------ int ReadMessage(MESSAGE *msg,int msgnum); ------------------------------------------------------------------ Reads message number <msgnum> into the MESSAGE structure. To access the text of the message, use the function CreateMessageText(). See the file PB_SDK.H for a description of the MESSAGE structure. Return value: -1 if the message does not exists 0 if the message is read ok ------------------------------------------------------------------ void WriteMSGTMP(char *text); ------------------------------------------------------------------ Writes the string <text> to the file MSGTMP. The file is always recreated when using this function. To append text to MSGTMP, use the function AppendMSGTMP(). You have to insert your own CR/LF pairs in the text if you want to force a newline. Lines can be longer than 80 characters. The message processing functions will do a word-wrap if necessary. Do NOT insert a single CR or LF in the text. (\r or \n). ------------------------------------------------------------------ void AppendMSGTMP(char *text); ------------------------------------------------------------------ Same as WriteMSGTMP(), but adds text to an EXISTING file. - 10 - ------------------------------------------------------------------ void ShowMessage(MESSAGE *msg); ------------------------------------------------------------------ Shows the message <msg> to the user, including header and message text. See the file PB_SDK.H for an description of the MESSAGE structure. ------------------------------------------------------------------ void CreateMessageText(MESSAGE *msg); ------------------------------------------------------------------ Reads the text that belongs to message <msg>, and stores it in a file called MSGTMP in the current directory. This file can then be accessed as an ordinary textfile. ------------------------------------------------------------------ void CreateMessageTextString(MESSAGE *msg,char *text,int max); ------------------------------------------------------------------ Reads the text that belongs to message <msg>, and stores it in the string <text>. The text will be terminated by a '\0' character. You have to specify a maximum number of characters that can be stored in <text>. - 11 - ------------------------------------------------------------------ int FirstMessage(MESSAGE *msg,int area,int order,int first); int NextMessage(MESSAGE *msg,int area,int order); ------------------------------------------------------------------ These functions are used to read messages in forward or reverse order. To start scanning messages, you have to call the FirstMessage() function first, and the NextMessage() function to read more messages. msg = MESSAGE structure where the message has to be stored. area = area number to read messages in (0 = all areas) order = 1 for forward order, -1 for reverse order first = message to start reading from. This message does NOT need to exist. The first non-deleted message following this message will be read first. See the file PB_SDK.H for an description of the MESSAGE structure. Return value: -1 No more messages found. >0 Message number of message found. This is an example on how to use these functions: result = FirstMessage(msg,0,+1,1); while(result >= 0) { /* Do something with the message */ result = NextMessage(msg,0,+1); } ------------------------------------------------------------------ void DeleteMessage(MESSAGE *msg); ------------------------------------------------------------------ Deletes message <msg>. ------------------------------------------------------------------ void MarkMessage(int msgnum); ------------------------------------------------------------------ Marks message number <msgnum> for later retrieval. Up to 200 messages can be marked. - 12 - ------------------------------------------------------------------ void ReadMarkedMessages(void); ------------------------------------------------------------------ Shows all marked messages to the user, with the option to wait after each message. If the user selected to wait after each message, the standard message options menu will be shown to the user. (Next,Prev,Stop,...). In fact, this function is identical to menu function "Read Messages", with the user selecting "Marked". ------------------------------------------------------------------ void ListMarkedMessages(void); ------------------------------------------------------------------ Is similar to ReadMarkedMessages(), but this function acts as a "QuickScan Messages" with the user selecting "Marked". ------------------------------------------------------------------ void UnMarkAllMessages(void); ------------------------------------------------------------------ Unmarks all messages that were previously marked. You have to call this function before marking any messages, because the list of marked messages is remembered until a user logs off. ------------------------------------------------------------------ int FuzzySearch(char *text,char *string,int degree); ------------------------------------------------------------------ Performs a fuzzy search for <string> in <text>. <degree> is the percentage of the characters in <string> that have to match. Return value: -1 if not found >0 percentage of characters matched - 13 - ------------------------------------------------------------------ IO_... functions ------------------------------------------------------------------ All functions starting with IO_ are low-level functions to access the serial port directly. Do NOT use these functions for ordinary I/O operations. They are intended for writing file transfer protocols. See the file PB_SDK.H for a description of these functions. ------------------------------------------------------------------ char WaitKey(void); ------------------------------------------------------------------ Waits for a character to be read from the modem or local keyboard. Return value: the character read. ------------------------------------------------------------------ char WaitKeys(char *keylist); ------------------------------------------------------------------ Waits for any character specified in <keylist>. Return value: the key from the list that was pressed (converted to uppercase if the key is a letter). Example : c = WaitKeys("ABC\r\x1b"); /* Waits for A,B,C,<Enter> or <Esc> */ - 14 - ------------------------------------------------------------------ void Input(char *buf,int len,int readmode); ------------------------------------------------------------------ Asks for a string from the user. The string is stored in <buf>, and the user will not be allowed to enter more than <len> characters. <readmode> : INPUT_ALL : All characters are allowed INPUT_UPFIRST : First character of each word is converted to uppercase. INPUT_UPALL : All characters are converted to uppercase. INPUT_DIGITS : Only digits are accepted. INPUT_NOFIELD : OR together with any of the previous modes if you don't want an input-field background to be displayed. ------------------------------------------------------------------ bool Ask(bool default); ------------------------------------------------------------------ Asks for a Yes or No response from the user. Pressing 'Y' returns TRUE and outputs "Yes". Pressing 'N' returns FALSE and sends "No" to the user. Pressing <Enter> returns <default>, and sends "Yes" or "No", depending on <default>. ------------------------------------------------------------------ char PeekChar(void); ------------------------------------------------------------------ Checks if a character is available in the input buffer, and returns that character if there is. Return value: 0 if no character available != 0 the character read (key pressed by user) - 15 - ------------------------------------------------------------------ void SetColor(char color); ------------------------------------------------------------------ Changes the current output color. All text that is output after this function is called will be displayed in the specified color. This function does nothing when the user does not have ANSI or AVATAR enabled. <color> can be one of the following: BLACK , RED , GREEN , YELLOW , MAGENTA , BLUE , CYAN , WHITE ------------------------------------------------------------------ void SetfullColor(unsigned char color); ------------------------------------------------------------------ Changes the current foreground & background color. The color code is an IBM-type screen color code. This function does nothing when the user does not have ANSI or AVATAR enabled. Some examples: 0x1E : Bright yellow on dark blue background. 0x87 : Blinking white on a black background. ------------------------------------------------------------------ void GotoXY(int x,int y); ------------------------------------------------------------------ Moves the cursor to position (x,y). The upper left corner of the screen is (1,1). This function does nothing when the user does not have ANSI or AVATAR enabled. ------------------------------------------------------------------ void ClrEol(); ------------------------------------------------------------------ Clears from the current cursor position to the end of the line. This function does nothing when the user does not have ANSI or AVATAR enabled. - 16 - ------------------------------------------------------------------ void EnableStop(void); void DisableStop(void); bool Stopped(void); ------------------------------------------------------------------ Enables stopping of output by pressing 'S'. When enabled, a user can press 'S' to stop incoming text. When this happens, any string output function will immediately return to the caller, en the function Stopped() will return TRUE to indicate that the user requested to stop output. EnableStop() Enables this feature and sets the "stopped" status to FALSE . DisableStop() Disables the stop feature. Stopped() Returns the "stopped" flag (TRUE or FALSE). Example: EnableStop(); for(i=0;i<100;i++) { printf("...something..."); if(Stopped()) break; } ------------------------------------------------------------------ char ShowHotkeyFile(char *filename,char *hotkeys); ------------------------------------------------------------------ Shows the file <filename> to the user, and watches for incoming keys that are specified in <hotkeys>. If one of these keys is detected, the function stops output, and returns the hotkey. The "stop" feature will be enabled when sending the file. Return value: 0 : File sent completely and no hotkeys pressed. 1 : 'S' pressed (output stopped) 2 : File not found !=2 : Hotkey detected - 17 - ------------------------------------------------------------------ char ShowHotkeyANSIFile(char *filename,char *hotkeys); ------------------------------------------------------------------ This function is identical to ShowKotkeyFile(), except for the fact that no extension and path can be specified. Depending on the setting of the user, <filename>.ANS/ASC in the textfiles directory will be sent. If no .ANS file is found, it will try to send the .ASC file. If that fails too, 2 will be returned. Return value: 0 : File sent completely and no hotkeys pressed. 1 : 'S' pressed (output stopped) 2 : File not found !=2 : Hotkey detected ------------------------------------------------------------------ void InitLineCounter(void); bool LineCounter(void); ------------------------------------------------------------------ These functions are used to support page pausing ("More Y/N"). Calling InitLineCounter() initializes the line counter to 0. Every time you call LineCounter(), the line counter is incremented by one. If the counter reaches the screen length, the user will be asked if he wants to continue reading. If he selects "No", the LineCounter() function will return FALSE. Example: InitLineCounter(); for(;;) { printf("...something...\n"); if(!LineCounter()) break; } ------------------------------------------------------------------ bool ExternalInput(void); ------------------------------------------------------------------ Returns TRUE when the last character that was read through any of the input routings originated from the remote keyboard (ie. the sysop did not type it). - 18 - ------------------------------------------------------------------ int ReadUser(USER_REC *rec,int recnr); ------------------------------------------------------------------ Reads user record number <recnr> (0-...) from the user file and stores it in <rec>. Return value: -1 if record does not exist. 0 if record is read ok. ------------------------------------------------------------------ void WriteUser(USER_REC *rec,int recnr); ------------------------------------------------------------------ Writes user record <rec> to record number <recnr> in the userfile. ------------------------------------------------------------------ char PlayMusic(char *filename,char *hotkeys); ------------------------------------------------------------------ Plays a .MUS file. The file has to be located in the ProBoard system directory. Do not include a path and extension in <filename>. The music can be stopped if the sysop presses one of the keys specified in <hotkeys>. ^^^^^ Return value: 0 Music file played till the end 1 Music file not found >1 The hotkey pressed by the SYSOP ^^^^^ ------------------------------------------------------------------ void PostInfo(char *filename); ------------------------------------------------------------------ Does exactly the same as the POSTINFO statement in a .Q-A file. No path and extension is allowed in <filename>. The file where the information will be written to will have the extension .ASW and will be placed in the ProBoard system directory. - 19 - ------------------------------------------------------------------ int ReadFileArea(int areanum,FILEAREA *fa); ------------------------------------------------------------------ Reads information about file area number <areanum> in the <fa> structure. Check the file PB_SDK.H for details about the FILEAREA structure. Return value: -1 File area does not exist 0 Ok ------------------------------------------------------------------ void MenuFunction(int function,char *data); ------------------------------------------------------------------ Executes menu function <function> with <data>. For details, see the menu functions description in this file. There are named constants declared for each function in the file PB_SDK.H. It is recommended that you use these constants instead of numbers. ------------------------------------------------------------------ void Log(int loglevel,char *fmt,...); ------------------------------------------------------------------ With this function you can write information to the ProBoard logfile. The log entry will be written if the user has a loglevel that is greater than <loglevel> . <loglevel> can be one of the following: LOG_FRIEND , LOG_NORMAL , LOG_SUSPICIOUS , LOG_DANGEROUS If you want a log entry to be written regardless of the user's loglevel, use LOG_FRIEND. The Log() function works like the printf function: you can use format specifiers in the <fmt> string, and pass extra parameters. Example: Log(LOG_NORMAL,"User's name = %s",CurUser->name); - 20 - ------------------------------------------------------------------ void HangUp(); ------------------------------------------------------------------ Hangs up the phone, logging off the user. It is exactly the same as pressing Alt-H. ------------------------------------------------------------------ bool CheckAccess(int level,long flags); ------------------------------------------------------------------ Checks if the current user can access something that requires <level> and <flags>. Returns TRUE if the user has access, FALSE if not. ------------------------------------------------------------------ KEY ScanKey(void); ------------------------------------------------------------------ Checks the LOCAL keyboard for a key, and returns the scan code for that key. If no key is available, 0 will be returned. For a list of defined values for scan codes, check the file PB_SDK.H. ------------------------------------------------------------------ bool GetFlag(long flags,char flagchar); void SetFlag(long flags,char flagchar); void ClearFlag(long flags,char flagchar); ------------------------------------------------------------------ Access flags are stored in a long integer (32 bits). You have 3 macros at your disposal to manipulate access flags: GetFlag : Returns TRUE if flag <flagchar> is set SetFlag : Turns flag <flagchar> on ClearFlag : Turns flag <flagchar> off <flagchar> must be a value from 1 to 32. 1-26 correspond to A-Z, while 27-32 are the same as 1-6. - 21 - ------------------------------------------------------------------ int ErrorLevel(void); ------------------------------------------------------------------ Returns the errorlevel of the last executed shell command (Through MenuFunction(MENU_SHELL,...)) ------------------------------------------------------------------ bool GetIniVar(char *fname,char *varname,char *value,int max); bool SetIniVar(char *fname,char *varname,char *value); ------------------------------------------------------------------ These functions can be used to read and write to .INI files. These files are similar to the files used by MS Windows. They can be used to store settings for your application (PEX). An example of a .INI file: DataPath = C:\PB\PEX\MYPEX\DATA ProgPath = C:\PB\PEX\MYPEX MaxUsers = 10 This is a standard ASCII file, with each line in the form <varname> = <value> The value of a specific variable can be read by calling the function GetIniVar(). Setting a variable (writing to the .INI file or createing it if it doesn't exist yet) can be done by calling SetIniVar(). The parameters for the functions are: <fname> Name of the .INI file. The extension of the file will always be changed to .INI by ProBoard. <varname> Name of the variable (case INsensitive) <value> For GetIniVar() : a pointer to a buffer where the variable's contents will be stored. For SetIniVar() : a pointer to the value of the variable. <max> Maximum number of characters that can be copied in <value> (including trailing '\0') Return value: FALSE if the file could not be opened or the variable does not exist. - 22 - ------------------------------------------------------------------ void exit(void); ------------------------------------------------------------------ Exits the current pex-program, and unloads it from memory. ------------------------------------------------------------------ void ExitTSR(void); ------------------------------------------------------------------ Exits the current pex-program, and leaves it resident. This has some important implications: - All global and static variables keep their values for subsequent executions. - When the same pex-file is run again through menu function 60, the resident copy will be executed. This will result in faster loading. If you set up any handlers, you MUST use ExitTSR() to exit the program. ------------------------------------------------------------------ int InstallHandler(int handler,function); ------------------------------------------------------------------ This is probably the most advanced and complicated function in the ProBoard SDK. With this function you can set up a "handler" for a specific action. Right now, only two types of handlers are supported: a replacement for the sysopkey-handler and a handler to intercept loss of carrier. This way you can create your own sysopkeys, or change the behaviour of existing sysopkeys. You could create a handler that intercepts the Alt-J key, and write your own flavor. In future versions you will be able to set up handlers for low-level I/O operations. So you could replace all I/O routines by your own functions. This way you can support your own exotic hardware or something like that. Anything goes! handler : Handler type. At this time, only HANDLER_SYSOPKEY and HANDLER_HANGUP are supported. function : A pointer to the handler function you created. Return value : -1 if illegal handler number is specified 0 if ok - 23 - The handler function is a function that returns an integer. The parameters depend on the type of handler you are creating. For HANDLER_SYSOPKEY the handler function has to be declared like this: int sysopkeyhandler(KEY k) { ... } A sysopkey handler intercepts any special key that is pressed by the sysop. (like F1,Alt-H,...). You can redefine any key, or add your own. For HANDLER_HANGUP, the handler functions has to be declared like this: int hanguphandler(void) { ... } The hangup handler works a little different: it is called whenever ProBoard exits (carrier lost, sysop hung up,...). It can be used to perform some cleanup for your running PEX file (like closing files, writing data, etc..). You can install the handler at the start of your program and remove it before the program is finished. - 24 - If a handler function decides to do anything, it has to return HANDLED. If the handler wants to leave it up to ProBoard, it must return NOT_HANDLED. This asks for an example I suppose: int keyhandler(KEY k) { if(k == KEY_ALTJ) { printf("\7\rHang on %s! I'm shelling to DOS...",UserFirstName); MenuFunction(MENU_SHELL,"*N*Q*X*!"); printf("I'm back!!\n"); return HANDLED; } else return NOT_HANDLED; } main(int argc,char *argv[]) { InstallHandler(HANDLER_SYSOPKEY,keyhandler); ExitTSR(); /* IMPORTANT */ } So what does it do? It intercepts the sysopkey-function, and checks if the key pressed is Alt-J. If it is, it shells to DOS with swapping ON, and it writes its own messages to the screen. When the sysop returns, the handler returns HANDLED to let ProBoard know that it does not have to process the key. You could use this example in an INIT.PEX file. Is this powerful or what? ------------------------------------------------------------------ void RemoveHandler(int handler); ------------------------------------------------------------------ Removes handler number <handler> which has been installed by InstallHandler(). - 25 - ┌──────────────────────────────────────────────────────────────────┐ │ Global ProBoard Variables │ └──────────────────────────────────────────────────────────────────┘ You have access to some important ProBoard system variables through global variables defined in PB_SDK.H. ------------------------------------------------------------------ USER_REC * CurUser; ------------------------------------------------------------------ Pointer to the current user record. You can change any of the field values in the record, but this will not result in any immediate action by ProBoard. For example, if you change the user's level, ProBoard will not know that you changed it, so you will have to tell it by calling AdjustTime(); Check the file PB_SDK.H for a description of the USER_REC structure. ------------------------------------------------------------------ int UserRecNr; ------------------------------------------------------------------ The record number of the current user's record in the file USERS.BBS. This value cannot be changed. ------------------------------------------------------------------ int NumLimits; ------------------------------------------------------------------ The number of user levels defined in ProCFG. You can access the limit-values through the global array 'Limits'. This value cannot be changed. ------------------------------------------------------------------ LIMIT * Limits; ------------------------------------------------------------------ - 26 - Is an array of all user levels defined, with download and time limits. Check the file PB_SDK.H for information on the LIMIT structure. You are not allowed to change any values! (A good compiler should generate an error or warning if you try to do so) ------------------------------------------------------------------ char * LoginDate; char * LoginTime; ------------------------------------------------------------------ This is the login date & time of the current user. LoginDate[0] : Day portion of login date LoginDate[1] : Month portion of login date LoginDate[2] : Year portion of login date (00-99) LoginTime[0] : Hour portion of login time LoginTime[1] : Minute portion of login time LoginTime[2] : Second portion of login time ------------------------------------------------------------------ bool NetEntered; bool EchoEntered; ------------------------------------------------------------------ These READ-ONLY variables tell you if netmail or echomail has been entered during this session. ------------------------------------------------------------------ int NumUsers; ------------------------------------------------------------------ This READ-ONLY variable is the number of users currently available in the file USERS.BBS. ------------------------------------------------------------------ int NodeNumber; ------------------------------------------------------------------ This READ-ONLY variable is the current node number. - 27 - ------------------------------------------------------------------ char * CurMenu; char * UserFirstname; char * PrevUser; char * StartupPath; char * SysPath; ------------------------------------------------------------------ CurMenu : Current menu name UserFirstName : First name of current user PrevUser : Name of previous user StartupPath : Name of the directory where ProBoard was started from (with trailing '\') SysPath : Name of the ProBoard system directory (with trailing '\') These are READ-ONLY strings! ------------------------------------------------------------------ CONFIG * Config; ------------------------------------------------------------------ A pointer to the current ProBoard configuration structure. See the file PB_SDK.H for a description of the CONFIG structure. - 28 - ┌──────────────────────────────────────────────────────────────────┐ │ Special-purpose PEX-files │ └──────────────────────────────────────────────────────────────────┘ Several pex-files will be loaded automatically (if present). They perform certain actions like edit a message, set up handlers, etc. INIT.PEX : Will be loaded and executed before any I/O has been done. Use this to set up any handlers (sysopkey handlers, ...) INIT_1.PEX - INIT_9.PEX : Is the same as INIT.PEX, but will be loaded in the order of the numbers. So you can have up to 10 initialization pex-files. LOGIN.PEX : Is run just before the user is asked for his/her name. BIRTHDAY.PEX : Is run after showing NEWS.ANS/ASC if today is the user's birthday. NEWUSER1.PEX : Is run before the file NEWUSER1.ANS/ASC is shown. NEWUSER2.PEX : Is run before the file NEWUSER2.ANS/ASC is shown. WELCOME.PEX : Is run before the file WELCOME.ANS/ASC is shown WELCOMEx.PEX : Is run before the file WELCOMEx.ANS/ASC is shown (x = 1 to 9) SECxx.PEX : Executed when a user with security level xx logs in. Is run before SECxx.ANS/ASC is shown. EXPIRED.PEX : Is run before EXPIRED.ANS/ASC is shown, and after a user's level is lowered because the subscription date was reached. GOODBYE.PEX : Is run before GOODBYE.ANS is displayed. GOODBYE2.PEX : Is run after GOODBYE.ANS is displayed. - 29 - MSGED.PEX : Is a replacement of the built-in message editor. It will be executed with no parameters. The message that you create has to be written to a file called MSGTMP. ProBoard will then read this file and create a message from it. To let ProBoard know that the user has aborted a message, delete MSGTMP. FSED.PEX : Is similar to MSGED.PEX, but will be executed if the user has selected the fullsrceen editor. It works the same way as MSGED.PEX, but ProBoard will create a MSGTMP file with the original message if a user is replying to a message. - 30 - - 31 -